// Copyright (c) Appeon. All rights reserved.
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. 
// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

namespace SnapObjects.Data
{
    /// <summary>
    ///     Represents an object that can package multiple types of data element together.
    /// </summary>
    public interface IDataPacker
    {
        /// <summary>
        ///     Gets the number of elements that have been added into the IDataPacker object..
        /// </summary>
        int Count { get; }

        /// <summary>
        ///     Gets the keys for the elements which have been added into the IDataPacker object.
        /// </summary>
        string[] Keys { get; }

        /// <summary>
        ///     Gets the raw string of text which contains all of the elements in the IDataPacker object.
        /// </summary>
        string Raw { get; }

        /// <summary>
        ///     Gets the format of the text specified when creating the IDataPacker object.
        /// </summary>
        DataFormat DataFormat { get; }

        /// <summary>
        ///     Checks whether a specified element exists in the current IDataPacker object.
        /// </summary>
        /// <param name="key">The key of the element to look for.</param>
        /// <returns>Returns true if the element exists; otherwise, false.</returns>
        bool ContainsKey(string key);

        /// <summary>
        ///     Removes the specified element from the IDataPacker object.
        /// </summary>
        /// <param name="key">The key of the element to remove.</param>
        /// <returns>Returns true if the element is successfully removed; returns false if the element was not found.</returns>
        bool RemoveKey(string key);

        /// <summary>
        ///     Add a raw text string as an element to the IDataPacker object.
        /// </summary>
        /// <param name="key">The key for the element, which is the identifier of the element in the IDataPacker object.</param>
        /// <param name="value">The raw text string, which is the value of the element to be added to the IDataPacker object.</param>
        void AddRaw(string key, string value);

        /// <summary>
        ///     Gets a string in the specified format which represents all elements in the current IDataPacker object.
        /// </summary>
        /// <param name="format">
        ///     The format of the text string you want to get.
        ///     It supports DataFormat.Json and DataFormat.Xml so far.
        /// </param>
        /// <returns>Returns the string of text in the specified format.</returns>
        string GetTextString(DataFormat format);

        /// <summary>
        ///     Gets the raw string of text for the specified element.
        /// </summary>
        /// <param name="key">The key specifying which element to get the raw string of text.</param>
        /// <returns>Returns the raw string of text for the element if the key exists; otherwise, returns String.Empty.</returns>
        string GetRaw(string key);
    }
}
